Pyramid's exposes REST APIs for any programming environment that supports standard REST calls via HTTP. The REST APIs are built using the Swagger OpenAPI standard. APIs can also be accessed using a client SDK as of version 3 onwards.
REST Framework
The REST implementation, while generally standard, varies between the different API versions offered by Pyramid.
- Versions 1 (deprecated) and 2 use a technique without HTTP headers
- Version 3 uses HTTP headers
The following explains how to use the framework.
Get vs POST
Classic REST APIs typically use GET templates to drive functionality. However, this approach is best suited for simplistic functions and is inherently weak when there are multiple method parameters (which is usually too long for GET URLs) and if the parameter objects are richer with multiple (nested) property options and settings.
The limitations of the GET approach are further compounded by the security authorization mechanics needed to govern access to a system like Pyramid. All API actions in Pyramid need to have an authorization token to ensure the right user can perform the right action. As such, Pyramid's API is modeled on a "POST" model, where JSON data objects are posted in the API method calls facilitating the larger, more complex nested objects (in JSON).
Method Verbs
The more standardized approach to REST uses classic verb structures (Add / Edit / Delete etc) for different objects. Since the objects in Pyramid contain a significant number of properties and there are complexities around security and API operation, Pyramid has decided on a "direct method" approach to the API methods instead to simplify implementation of the API and associated activities.
Setting Access Tokens
Access tokens to use APIs are themselves derived from authentication API calls. The various techniques reflect the different SSO models that might be used on Pyramid. However, there is a subtle difference for how the tokens are used on all subsequent API calls:
- In API versions 1 and 2, security tokens are included in the HTTP request payload itself.
- In API version 3, the security token needs to be injected in the HTTP header, under a value called "PaToken."
To get a better sense for the difference, compare examples between API 2 and 3.
API Response Status
When an API is called a status of the call is usually given within the response. The API documentation highlights the response of successful calls. The list of all HTTP standard status values and their associated codes, including unsuccessful calls, is provided here.
API 3 introduces a slightly different methodology compared to the older versions.. In most cases, successful requests return the expected outcome (such as query results or modified IDs), while an error message is returned as a textual response for failed requests. The determination of a request's success relies on the corresponding HTTP response code. For backward compatibility, certain functions yield an object indicating the operation's success, which might be partial (for example, some roles were created while others failed).